home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / ezy_comm / ezy1023.zip / EKIT102.ZIP / EZYMSG.DOC < prev    next >
Text File  |  1992-10-24  |  16KB  |  442 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.                                      Ezycom
  15.  
  16.                             Message Base Structures
  17.  
  18.                               Specifications V1.02
  19.  
  20.                         Copyright (C) Peter Davies 1992.
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.           Table of Contents
  28.  
  29.  
  30.           1.0 Legal Aspects
  31.  
  32.           2.0 Specifications
  33.                2.1 Pascal Structures
  34.                2.2 C Structures
  35.  
  36.           3.0 Message Base in Detail
  37.                3.1 Overview
  38.                3.2 Message Header
  39.                3.3 Message Text
  40.                3.4 MSGFAST.BBS (Fast Mail Check Index)
  41.                3.5 MSGCOUNT.BBS (Message Area Number of Messages)
  42.                3.6 MSGEXPORT.BBS (Message Area requires Scan)
  43.                3.7 MSGREPLY.BBS (Message Area requires Reply Chaining)
  44.                3.8 Pascal Strings
  45.  
  46.           4.0 Conclusion
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.           1.0 Legal Aspects
  54.  
  55.                These structures and specifications remain the
  56.           copyrighted works of Peter Davies.  They are freely
  57.           available for use by anyone, but must be used in an
  58.           unchanged format.  Also, to use these structures, you must
  59.           completly implement them, to keep direct compatibility with
  60.           the message base structures.
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.           2.0 Specifications
  68.  
  69.                2.1 Pascal Structures
  70.  
  71.           type
  72.              netrecord = record
  73.                 zone,
  74.                 net,
  75.                 node,
  76.                 point    : word
  77.              end;
  78.  
  79.              userstring = string[35];
  80.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86.           (*
  87.           **********************************************************
  88.  
  89.           Filename:     <msgpath>\AREA<<area-1>/4+1>\MSGH<area>.BBS
  90.  
  91.           Description:  Used by Ezycom to store message header
  92.  
  93.  
  94.           **********************************************************
  95.           *)
  96.  
  97.                   msghdrrecord   = record
  98.                      prevreply,
  99.                      nextreply      : word;
  100.                         (* 0 = No Reply Chain *)
  101.                      startposition,
  102.                         (* Physical Start Position in MSGTxxx.BBS *)
  103.                      messagelength  : longint;
  104.                        (* Message Length including Null Terminator *)
  105.                      destnet,
  106.                      orignet        : netrecord;
  107.                      cost           : word;
  108.                      msgattr,
  109.                         (*  Bit 0 : Deleted
  110.                                 1 : Netmail pending export
  111.                                 2 : [Reserved]
  112.                                 3 : Private
  113.                                 4 : Received
  114.                                 5 : Echomail pending export
  115.                                 6 : Locally generated msg
  116.                                 7 : Do not kill message *)
  117.                      netattr,
  118.                         (*  Bit 0 : Kill/sent
  119.                                 1 : Sent
  120.                                 2 : File Attach
  121.                                 3 : Crash
  122.                                 4 : File Req
  123.                                 5 : Request Receipt
  124.                                 6 : Audit Request
  125.                                 7 : Is a Return Receipt *)
  126.                      extattr   : byte;
  127.                         (*  Bit 0-7 [Reserved] *)
  128.                      posttimedate : longint;
  129.                         (* DOS Format Packed DateTime *)
  130.                      recvtimedate : longint;
  131.                         (* DOS Format Packed DateTime *)
  132.                      whoto,
  133.                      whofrom        : userstring;
  134.                      subject        : string[72];
  135.                   end;
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.           (*
  143.           **********************************************************
  144.  
  145.           Filename:     <msgpath>\AREA<<area-1>/4+1>\MSGT<area>.BBS
  146.  
  147.           Description:  Used by Ezycom to store message text
  148.  
  149.           **********************************************************
  150.           *)
  151.  
  152.           (* Message Text
  153.  
  154.                Each text part of the message starts at
  155.           'startposition', and continues on until a NULL terminator is
  156.           found, or end of file is reached (shouldn't happen, but just
  157.           in case).  The message text length is limited by Turbo
  158.           Pascal to 16 Meg in size.  Each message is contained of
  159.           plain text, with 0x08D terminators for wrapped lines or 0x0D
  160.           terminators for hard carriage returns.  No line of text
  161.           should exceed 79 characters excluding the terminator *)
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.           (*
  169.           **********************************************************
  170.  
  171.           Filename:     <msgpath>MSGFAST.BBS
  172.  
  173.           Description:  Used by Ezycom for mail checks
  174.  
  175.  
  176.           **********************************************************
  177.           *)
  178.  
  179.                   msgfastrecord  = record
  180.                      whoto     : longint;
  181.                         (* standard 32 Bit CRC on whoto in MSGH???.BBS
  182.                            Username is CRCd in UPPERCASE, and does not
  183.                            include null terminator or length byte *)
  184.                      msgboard  : word;
  185.                      msgnumber : word;
  186.                   end;
  187.  
  188.           (*
  189.           **********************************************************
  190.  
  191.           Filename:     <msgpath>MSGEXPRT.BBS
  192.  
  193.           Description:  Used by Ezycom to tell EzyNet/EzyMail whether
  194.                         an area needs scanning or not
  195.  
  196.  
  197.           **********************************************************
  198.           *)
  199.  
  200.                   needscanrecord = array[1..maxmess] of boolean;
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.           (*
  208.           **********************************************************
  209.  
  210.           Filename:     <msgpath>MSGREPLY.BBS
  211.  
  212.           Description:  Used by MsgComp to tell it which conference(s)
  213.                         need reply chain linking
  214.  
  215.           **********************************************************
  216.           *)
  217.  
  218.                   needreplytype   = array[1..maxmess] of boolean;
  219.  
  220.           (*
  221.           **********************************************************
  222.  
  223.           Filename:     <msgpath>MSGCOUNT.BBS
  224.  
  225.           Description:  Used by Ezycom and Utilities for message area
  226.                         counting.  You must lock EACH two bytes, then
  227.                         update/read it, then unlock it to update a
  228.                         message area count.  Reading the number of
  229.                         records of MSGHxxx.BBS gives the same effect
  230.                         as reading the conferences count.
  231.  
  232.           **********************************************************
  233.           *)
  234.  
  235.                   msgareacounttype = array[1..maxmess] of word;
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.           3.0 Message Base in Detail
  243.  
  244.                3.1 Overview
  245.  
  246.                Ezycom message base is stored in paths off of the
  247.           message base directory.  These paths contain 100 message
  248.           areas.  They are named AREA1, AREA2 and so forth.  AREA1
  249.           will contain message areas 1 through to 100.  AREA2 will
  250.           contain message areas 101 through to 200 and so on.
  251.  
  252.                For each of the message areas, two files exist.
  253.           MSGHxxx.BBS and MSGTxxx.BBS.  The MSGHxxx.BBS is the header
  254.           file for the message area and the MSGTxxx.BBS is the text
  255.           file for the message area.  The xxx is the message area
  256.           number "0" padded.  So, message area 1 would be MSGT001.BBS
  257.           for example.  Message areas 1000 and above use a forth
  258.           digit, and are named as MSGHxxxx.BBS and MSGTxxxx.BBS.  An
  259.           example for message area 1010 would be MSGH1010.BBS.
  260.  
  261.                3.2 Message Header
  262.  
  263.                This file contains the "Header" information of each
  264.           message.  In contains information such as who the message is
  265.           from, to, subject, reply chain information, and other
  266.           attributes.  When opening up this message area, it should
  267.           ALWAYS be opened in a DENYNONE mode.  I suggest when opening
  268.           it, you also open it in READWRITE mode, in case you need to
  269.           update any message attributes.  There is a possibility that
  270.           the message area doesn't exist, so make sure you check for
  271.           it.  Also, the message area may be 0 in length, so make sure
  272.           you check for that.
  273.  
  274.                The reply chains (prevreply, nextreply) point to the
  275.           previous message and next message in the reply chains
  276.           respectively.  A value of 0, means that there is no
  277.           previous/next reply chain respectively.  A value of 1, would
  278.           mean the message at record 0.  A value of 2, would mean the
  279.           message at record 1, and so on.
  280.  
  281.                StartPosition is the location in MSGTxxx.BBS where the
  282.           text starts for this message.  MessageLength is the length
  283.           in bytes of the message text including the null terminator
  284.           (explained later).
  285.  
  286.                OrigNet and DestNet contain fidonet addresses of who
  287.           the message came from, and who it is to for netmail message
  288.           areas.  OrigNet is also set for who the message came from,
  289.           on importing EchoMail with a valid MSGID kludge line.  These
  290.           should be zeroed out when not in use.  Cost is for netmail
  291.           areas, and specifically holds the cost of a message.
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.                The MsgAttr contains certain attributes of each
  299.           message.  Most are self explanatory, but a few details must
  300.           be explained.  Any message written locally, must have a
  301.           Local Bit Set.  Any message written in an echomail message
  302.           area, must have Echomail pending Export set, to tell the
  303.           echomail scanner that the message needs exporting.  Any
  304.           message written in a netmail message area, must have Netmail
  305.           pending Export set, to tell the netmail scanner that the
  306.           message needs exporting.
  307.  
  308.                The NetAttr simply holds netmail attributes, although
  309.           some are used (receipts) for local message areas in Ezycom.
  310.  
  311.                The ExtAttr is not currently used, but you should not
  312.           take the assumption that it is free for you to use, or else
  313.           your program might not be compatiable in later versions.
  314.  
  315.                Posttimedate is a DOS packed time and date of the
  316.           message.  DOS packed, is what MSDOS uses to store the date
  317.           of each file.  This was used to keep the message base as
  318.           small as possible.  Recvtimedate is simply the time and date
  319.           when the message was received.  The value is undefined if
  320.           the message has not been received.  This variable should be
  321.           used in conjunction with the Received Bit in MsgAttr.
  322.  
  323.                WhoTo, WhoFrom and Subject are simply who the message
  324.           is to, who the message is from and the subject.
  325.  
  326.                3.3 Message Text
  327.  
  328.                This file contains the textual part of the message.
  329.           When reading the MSGTxxx.BBS, it should be opened in a
  330.           DENYNONE and READONLY mode.  Any other method of opening
  331.           will stop other tasks accessing the message base.  When
  332.           writing the message (the time when it is physically being
  333.           written), the file should be opened in a DENYWRITE and
  334.           WRITEONLY mode.  This will stop any other tasks writing the
  335.           message at the same time.  The text for a new message should
  336.           be written before the header.  The header should be written
  337.           while the MSGTxxx.BBS is in a DENYWRITE and WRITEONLY mode.
  338.           All reply chains, MSGFAST, MSGCOUNT, MSGEXPRT should also be
  339.           updated while the MSGTxxx.BBS is locked for writing.  The
  340.           actual message text follows a specific format.  Each line of
  341.           text MUST be terminated by either an 0x08D or 0x0D.  The
  342.           0x08D indicates a soft carriage return, and is a movable
  343.           boundary, whereas the 0x0D indicates a hard carriage return,
  344.           and is not moveable.  The message text should end with a
  345.           null terminator (0x00), which aids reading infinately long
  346.           messages.
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.                3.4 MSGFAST.BBS
  354.  
  355.                This is an index for mail checks.  Simply scanning the
  356.           MSGHxxx.BBS for who the message was to, took to long, so
  357.           this index was made.  It is possible for you to scan the
  358.           MSGHxxx.BBS for mail checks, although unwise.  When writing
  359.           messages, this file MUST be updated, otherwise programs that
  360.           use this, will not see new messages for mail checks.  The
  361.           whoto field in the MSGFAST record, is a standard 32 Bit CRC
  362.           of the users name.  The CRC generated, should be done on an
  363.           uppercase USERNAME, and should not include the PASCAL length
  364.           byte, or the C null terminator.  The initial starting
  365.           position for the CRC is the usual 0x0FFFFFFFF ($FFFFFFFF).
  366.           The msgboard variable holds the number of the message board
  367.           where this message exists.  The msgnumber variable holds the
  368.           record number of the message in the message board.  It
  369.           should be noted that Ezycom optimizes this file, so that
  370.           received messages are not placed in this file.  This should
  371.           not concern the developer though.
  372.  
  373.                3.5 MSGCOUNT.BBS
  374.  
  375.                Since, Ezycom now uses 1024 message areas, it was
  376.           neccessary that a file be used to hold the number of
  377.           messages in each area.  This file should ALWAYS be opened in
  378.           a DENYNONE and READ/WRITE/READWRITE mode.  The only program
  379.           to completly lock this file is MSGCOMP, as it is packing the
  380.           message base, so simultaneous access is not possible.  It
  381.           should be noted that you can also obtain the number of
  382.           messages in an area by obtaining the filesize of the
  383.           MSGHxxx.BBS and dividing it by the size of the MSGHxxx.BBS
  384.           structure.
  385.  
  386.                3.6 MSGEXPRT.BBS
  387.  
  388.                This file simply holds a byte telling the
  389.           echomail/netmail scanner, which message areas require
  390.           scanning.  A value of 0 indicates that no scan is required,
  391.           whereas a value of 1 indicates a scan is required.  In
  392.           Pascal a value of 0 is defined as false, and a value of 1 is
  393.           defined as true.  This file should be updated, whenever a
  394.           message is written to a message area that is an
  395.           echomail/netmail area.
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.                3.7 MSGREPLY.BBS
  403.  
  404.                This file is similar to the previous, but holds which
  405.           message areas require reply chains.  If, your program
  406.           automatically does reply chaining (EZYUNIT.PAS does
  407.           automatic reply chaining), then you do not have to set this
  408.           bit.  Echomail tossers (EZYMAIL) and Offline Readers usually
  409.           set this, and reply chain linking is not possible.  The
  410.           message compacter (MSGCOMP) will pick up that the area needs
  411.           reply chaining, and hence chain messages with the same
  412.           subject together.
  413.  
  414.                3.8 Pascal Strings
  415.  
  416.                For those coding in C, the pascal string varies
  417.           slighty.  It does not include a null terminator, and has a
  418.           length byte (length of string) at position [0] of the
  419.           string, indicating its length.
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.           4.0 Conclusion
  427.  
  428.                The Ezycom message base is fairly simple in structure,
  429.           but offers a high performance when in use.  This gives
  430.           multiple line BBSs significant speed enhancement over other
  431.           message base structures.  If, you have any queries,
  432.           suggestions, etc please do not hesitate in contacting me.
  433.  
  434.           Peter Davies
  435.           PO Box 43
  436.           Bentleigh VIC 3204
  437.           Australia
  438.  
  439.           Fidonet  3:636/213
  440.           Internet daviesex@brt.deakin.edu.au
  441.  
  442.           BBS +61-3-578-0968 V22bis/V32 MNP4